From 65408a0b0c5c6fb74c246b44bae891311d361130 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 23 Oct 2017 05:46:58 +0200
Subject: [PATCH] Document new selection apis

Document the new cairo surface-based apis for GtkSelection.
---
 docs/reference/gtk/gtk4-sections.txt |  2 ++
 gtk/gtkselection.c                   | 28 ++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index f88b3bfcd8..38591fc66f 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -5247,6 +5247,8 @@ gtk_selection_data_set_text
 gtk_selection_data_get_text
 gtk_selection_data_set_pixbuf
 gtk_selection_data_get_pixbuf
+gtk_selection_data_set_surface
+gtk_selection_data_get_surface
 gtk_selection_data_set_uris
 gtk_selection_data_get_uris
 gtk_selection_data_get_targets
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 6590fac80e..611c09e677 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -1733,6 +1733,20 @@ gtk_selection_data_set_pixbuf (GtkSelectionData *selection_data,
   return FALSE;
 }
 
+/**
+ * gtk_selection_data_set_surface:
+ * @selection_data: a #GtkSelectionData
+ * @surface: a cairo image surface
+ * 
+ * Sets the contents of the selection from a cairo image surface.
+ * The surface is converted to the form determined by
+ * @selection_data->target.
+ * 
+ * Returns: %TRUE if the selection was successfully set,
+ *   otherwise %FALSE.
+ *
+ * Since: 3.94
+ **/
 gboolean
 gtk_selection_data_set_surface (GtkSelectionData *selection_data,
 			        cairo_surface_t  *surface)
@@ -1750,6 +1764,20 @@ gtk_selection_data_set_surface (GtkSelectionData *selection_data,
   return retval;
 }
 
+/**
+ * gtk_selection_data_get_surface:
+ * @selection_data: a #GtkSelectionData
+ * 
+ * Gets the contents of the selection data as a cairo surface.
+ * 
+ * Returns: (nullable) (transfer full): if the selection data
+ *   contained a recognized image type and it could be converted to a
+ *   cairo surface, a newly allocated surface is returned, otherwise
+ *   %NULL.  If the result is non-%NULL it must be freed with
+ *   g_object_unref().
+ *
+ * Since: 3.94
+ **/
 cairo_surface_t *
 gtk_selection_data_get_surface (GtkSelectionData *selection_data)
 {
-- 
2.30.2